/**
 * 版权所有(C)，上海勾芒信息科技，2017，所有权利保留。
 * 
 * 项目名：	cards-web
 * 文件名：	WxNetworking.java
 * 模块说明：	
 * 修改历史：
 * 2017年5月24日 - Debenson - 创建。
 */
package me.chanjar.weixin.common;

import java.io.File;
import java.io.InputStream;
import java.util.Map;

import org.apache.http.HttpHost;
import org.apache.http.impl.client.CloseableHttpClient;

import me.chanjar.weixin.common.exception.WxErrorException;
import me.chanjar.weixin.common.util.http.RequestExecutor;
import me.chanjar.weixin.common.util.http.RequestHttp;

/**
 * 提供微信网络相关接口
 * 
 * @author Debenson
 * @since 0.1
 */
public interface WxNetworking extends RequestHttp<CloseableHttpClient, HttpHost> {

  /**
   * @param url
   * @param queryParams
   * @return
   * @throws WxErrorException
   */
  public String httpGet(String url, Map<String, Object> queryParams) throws WxErrorException;

  /**
   * @param url
   * @param queryParams
   * @param respClazz
   *          返回值类型
   * @return
   * @throws WxErrorException
   */
  public <T> T httpGet(String url, Map<String, Object> queryParams, Class<T> respClazz)
      throws WxErrorException;

  /**
   * @param url
   * @param queryParams
   * @return
   * @throws WxErrorException
   */
  public String httpGet(String url, String queryParams) throws WxErrorException;

  /**
   * @param url
   * @param queryParams
   * @param respClazz
   *          返回值类型
   * @return
   * @throws WxErrorException
   */
  public <T> T httpGet(String url, String queryParams, Class<T> respClazz) throws WxErrorException;

  /**
   * @param url
   * @param postData
   * @return
   * @throws WxErrorException
   */
  public String httpPost(String url, String postData) throws WxErrorException;

  /**
   * @param url
   *          请求的url
   * @param postData
   *          请求体
   * @param respClazz
   *          返回值类型
   * @return
   * @throws WxErrorException
   */
  public <T> T httpPost(String url, Object postObj, Class<T> respClazz) throws WxErrorException;

  /**
   * 文件下载
   * 
   * @param url
   * @return
   * @throws WxErrorException
   */
  public File download(String url) throws WxErrorException;

  /**
   * 文件下载
   * 
   * @param url
   * @param post
   * @return
   * @throws WxErrorException
   */
  public InputStream httpPostForStream(String url, String post) throws WxErrorException;

  /**
   * <pre>
   * Service没有实现某个API的时候，可以用这个，
   * 比{@link #get}和{@link #post}方法更灵活，可以自己构造RequestExecutor用来处理不同的参数和不同的返回类型。
   * 可以参考，{@link me.chanjar.weixin.common.util.http.MediaUploadRequestExecutor}的实现方法
   * </pre>
   * 
   * @param executor
   * @param uri
   * @param data
   * @return
   * @throws WxErrorException
   */
  public <T, E> T execute(RequestExecutor<T, E> executor, String uri, E data)
      throws WxErrorException;

  /**
   * 每次尝试后的等待毫秒数
   * 
   * @return
   */
  public int getRetrySleepMillis();

  /**
   * 最大尝试次数
   * 
   * @return
   */
  public int getMaxRetryTimes();

  /**
   * 在url添加access token
   * 
   * @param url
   *          请求的url
   * @return 返回添加access token后的url
   * @throws WxErrorException
   */
  public String appendAccessToken(String url) throws WxErrorException;

  /**
   * 如果当前access token过期，则将access token重置
   * 
   * @param code
   *          access token
   * @return access token是否已经过期
   */
  public boolean expireIfInvalidToken(int code);

}
